package space.misiro.ledgers.middleware.api.domain.um

/**
 * 用户角色传输对象枚举
 *
 * 定义系统支持的各类用户角色及其对应的字符串标识值
 *
 * @property value 角色在传输过程中使用的字符串标识
 */
enum class UserRoleTO(val value: String) {
    /** 普通客户角色 */
    CUSTOMER("customer"),

    /** 内部员工角色 */
    STAFF("staff"),

    /** 技术支持角色 */
    TECHNICAL("technical"),

    /** 系统管理角色 */
    SYSTEM("system"),

    /** 默认角色（未明确指定时的默认值） */
    DEFAULT("default");

    companion object {
        /**
         * 包含所有角色名称的字符串列表
         *
         * 该列表通过映射枚举项名称生成，用于需要完整角色清单的场景
         */
        val ALL_ROLES: List<String> = entries.map { it.name }

        /**
         * 内部使用的值-枚举映射容器
         *
         * 通过关联枚举项的值与枚举实例构建，用于快速通过字符串值查找对应枚举
         */
        private val container: Map<String, UserRoleTO> = entries.associateBy { it.value }

        /**
         * 通过字符串值获取对应的枚举实例
         *
         * @param value 需要查找的字符串标识值
         * @return 匹配的UserRoleTO枚举实例
         * @throws RuntimeException 当传入不存在的枚举值时抛出异常
         */
        fun getByValue(value: String): UserRoleTO {
            return container[value] ?: throw RuntimeException("枚举值不正确")
        }
    }
}
